<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>ListView widget</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="Android, programming, ListView widget, tutorial, Java, mobile development">
<meta name="description" content="In this chapter of the Android tutorial, we will
work with ListView widget.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href=".." title="Home">Contents</a>


<h1>ListView widget</h1>


<p>
In this chapter of the Android development tutorial, we will explore
the ListView widget.
</p>

<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<p>
A <i>ListView</i> is a widget that shows items in a verticall scrolling
list. An <i>Adapter</i> object is used to fill the ListView with data.
</p>


<h2>ListView widget I</h2>

<p>
In the example, we show a ListView widget with the names
of the planets of our solar system. We use an ArrayAdapter to 
fill the ListView with data. 
</p>

<div class="codehead">main.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;  
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"  
  android:orientation="vertical"  
  android:layout_width="fill_parent"  
  android:layout_height="fill_parent"&gt;  
    
    &lt;ListView 
      android:id="@+id/lvId"
      android:layout_width="fill_parent"   
      android:layout_height="fill_parent" /&gt;  
    
&lt;/LinearLayout&gt; 
</pre>

<p>
In the <i>main.xml</i> file we define one ListView widget. 
</p>

<div class="codehead">row.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;TextView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:padding="10dp"
    android:textSize="20sp"&gt;
&lt;/TextView&gt;
</pre>

<p>
In the <i>row.xml</i> file we define, how a list row will look like. 
We will have one TextView in each row of a ListView. The sp is a unit
used for setting the font size.
</p>

<div class="codehead">strings.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
    &lt;string name="app_name"&gt;ListView&lt;/string&gt;
    &lt;string-array name="planets"&gt;
        &lt;item&gt;Mercury&lt;/item&gt;
        &lt;item&gt;Venus&lt;/item&gt;
        &lt;item&gt;Earth&lt;/item&gt;
        &lt;item&gt;Mars&lt;/item&gt;
        &lt;item&gt;Jupiter&lt;/item&gt;
        &lt;item&gt;Saturn&lt;/item&gt;
        &lt;item&gt;Uranus&lt;/item&gt;
        &lt;item&gt;Neptune&lt;/item&gt;
        &lt;item&gt;Pluto&lt;/item&gt;
    &lt;/string-array&gt;        
&lt;/resources&gt;
</pre>

<p>
The names of the planets are specified in the <i>strings.xml</i> file within 
a string array attribute.
</p>

<div class="codehead">MainActivity.java</div>
<pre class="code">
package com.zetcode.listview;

import android.app.Activity;
import android.os.Bundle;
import android.widget.ArrayAdapter;  
import android.widget.ListView;  

public class MainActivity extends Activity
{
    private ListView lv;  
    private ArrayAdapter&lt;String&gt; la; 

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        setupUI();
    }

    public void setupUI()
    { 
        lv = (ListView) findViewById(R.id.lvId);  
        String[] planets = getResources().getStringArray(R.array.planets); 
        lv.setAdapter(new ArrayAdapter&lt;String&gt;(this, R.layout.row, planets));
    }
}
</pre>

<p>
This is the MainActivity.java source file. 
</p>

<pre class="explanation">
lv = (ListView) findViewById(R.id.lvId);  
</pre>

<p>
We get the reference to the ListView widget.
</p>

<pre class="explanation">
String[] planets = getResources().getStringArray(R.array.planets);
</pre>

<p>
This code line retrieves the names of the planets from the resource file. 
</p>

<pre class="explanation">
lv.setAdapter(new ArrayAdapter&lt;String&gt;(this, R.layout.row, planets));
</pre>

<p>
An ArrayAdapter is created and set to the ListView.
</p>

<img src="/img/java/android/listview.png" alt="ListView widget">
<div class="figure">
Figure: ListView widget
</div>


<h2>ListView widget II</h2>
 
<p>
A <i>ListActivity</i> is a special activity that holds a ListView object.
ListView is a common widget and it typically takes the whole screen. Therefore
a special activity was created. In the example, the manifest file is not modified. 
We will also not need the main.xml layout file.
</p>

<div class="codehead">row.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;TextView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:padding="10dp"
    android:textSize="20sp"&gt;
&lt;/TextView&gt;
</pre>

<p>
In the <i>row.xml</i> file we define one TextView in each row of a ListView. 
</p>

<div class="codehead">strings.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
    &lt;string name="app_name"&gt;ListView2&lt;/string&gt;
&lt;/resources&gt;
</pre>

<p>
This is the <i>strings.xml</i> resource file. 
</p>


<div class="codehead">MainActivity.java</div>
<pre class="code">
package com.zetcode.listview2;

import android.app.ListActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.ArrayAdapter;  
import android.widget.AdapterView;
import android.widget.AdapterView.OnItemClickListener;
import android.widget.AdapterView.OnItemSelectedListener;
import android.widget.ListView;  
import android.widget.TextView;

public class MainActivity extends ListActivity 
     implements OnItemClickListener, OnItemSelectedListener
{       
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setupUI();
    }

    public void setupUI()
    { 
        ArrayAdapter&lt;String&gt; la = new ArrayAdapter&lt;String&gt;(this, R.layout.row);  
        la.add("Mercury");
        la.add("Venus");
        la.add("Earth");
        la.add("Mars");
        la.add("Jupiter");
        la.add("Saturn");
        la.add("Uranus");
        la.add("Neptune");
        la.add("Pluto");

        setListAdapter(la);

        ListView lv = getListView();
        lv.setOnItemClickListener(this);
        lv.setOnItemSelectedListener(this);
    }

    public void onItemClick(AdapterView&lt;?&gt; parent, View view,
        int position, long id) 
    {        
        String planet = ((TextView) view).getText().toString();
        setTitle(planet);
    }

    public void onItemSelected(AdapterView&lt;?&gt; parent, View view,
        int position, long id) 
    {        
        String planet = ((TextView) view).getText().toString();
        setTitle(planet);
    }

    public void onNothingSelected(AdapterView&lt;?&gt; parent) 
    {        
        // not implemented
    }
}
</pre>

<p>
We programatically create the items of the ListView. We react to click and select
events of the ListView. The planet that we select or click on will be shown in
the titlebar. 
</p>

<pre class="explanation">
public class MainActivity extends ListActivity 
     implements OnItemClickListener, OnItemSelectedListener
</pre>

<p>
The MainActivity extends the <code>ListActivity</code> and implements two listeners.
By implementing these two listeners, we must implement three abstract methods that
are associated with these listeners.
</p>

<pre class="explanation">
@Override
public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
    setupUI();
}
</pre>

<p>
In the onCreate() method we do not call the setContentView() method. 
The ListView widget of the ListActivity will take up the whole screen.
</p>

<pre class="explanation">
ArrayAdapter&lt;String&gt; la = new ArrayAdapter&lt;String&gt;(this, R.layout.row);  
la.add("Mercury");
la.add("Venus");
la.add("Earth");
...
</pre>

<p>
We create an instance of the <code>ArrayAdapter</code>. We add names of the planets
to the adapter.
</p>

<pre class="explanation">
setListAdapter(la);
</pre>

<p>
Sets the adapter for the associated ListView object.
</p>

<pre class="explanation">
ListView lv = getListView();
lv.setOnItemClickListener(this);
lv.setOnItemSelectedListener(this);
</pre>

<p>
From the ListActivity we get the ListView widget. The two listeners are
set for the ListView widget. 
</p>

<pre class="explanation">
public void onItemClick(AdapterView&lt;?&gt; parent, View view,
    int position, long id) 
{        
    String planet = ((TextView) view).getText().toString();
    setTitle(planet);
}
</pre>

<p>
Implementing the <code>OnItemClickListener</code>, we have to define the 
<code>onItemClick()</code> method. We get the planet name from the 
<code>TextView</code> of the clicked row and set it to the titlebar. 
</p>

<pre class="explanation">
public void onItemSelected(AdapterView&lt;?&gt; parent, View view,
    int position, long id) 
{        
    String planet = ((TextView) view).getText().toString();
    setTitle(planet);
}

public void onNothingSelected(AdapterView&lt;?&gt; parent) 
{        
    // not implemented
}
</pre>

<p>
After implementing the <code>OnItemSelectedListener</code> we have to
define two abstract methods. The first method sets the currently selected
planet to the titlebar. The second method is not implemented. 
</p>

<img src="/img/java/android/listview2.png" alt="Selected row of a ListView widget">
<div class="figure">
Figure: Selected row of a ListView widget
</div>

<p>
In this chapter of the Android development tutorial, we have mentioned 
the ListView widget.
</p>


<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div>
<br> 



<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified November 19, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>

